KGT allows ABNF style railroad diagrams

[mikesamuel]

Proposal

Using ABNF style syntax to derive railroad diagrams explaining parsing a formal language.

An existing tool katef/kgt allows syntax like the ABNF (full example file) to generate diagrams like the attached. It is already implemented and well tested. The tool should be repackagable as a WASM binary and invocable from within a webpage where it could be used to generate an SVG that can then be attached to the existing DOM.

Snippet of ABNF of a date-time grammar

; date and time format taken from RFC 5322.
; https://tools.ietf.org/html/rfc5322#section-3.3

date-time       =   [ day-of-week "," ] date time [CFWS]

day-of-week     =   ([FWS] day-name) / obs-day-of-week

day-name        =   "Mon" / "Tue" / "Wed" / "Thu" /
                    "Fri" / "Sat" / "Sun"

date            =   day month year

day             =   ([FWS] 1*2DIGIT FWS) / obs-day

month           =   "Jan" / "Feb" / "Mar" / "Apr" /
                    "May" / "Jun" / "Jul" / "Aug" /
                    "Sep" / "Oct" / "Nov" / "Dec"

...

(PR #4608 also proposed something similar but may have stalled. This would likewise address issue #4252.)

Use Cases

Mermaid used inside programming language documentation in eg mkdocs, including the Mermaid DSL documentation, showing full grammar diagrams.

Screenshots

No response

Syntax

I imagine mermaid would include a "grammar" diagram type.
As a minimal example, drawing on the ABNF from above, the keyword grammar would apply to the indented block following which, after extracting any mermaid preamble, would delegate to the KGT tool.

grammar
  date-time       =   [ day-of-week "," ] date time [CFWS]

  day-of-week     =   ([FWS] day-name) / obs-day-of-week

  day-name        =   "Mon" / "Tue" / "Wed" / "Thu" /
                      "Fri" / "Sat" / "Sun"
  
  ...

In addition to the example above, there is a directory of examples

https://katef.github.io/kgt/ is the documentation site and includes some examples.

Implementation

https://github.com/katef/kgt